<?php
/**
 * System module. Module loader and manager.
 *
 * @author Martin "DevelX" Jurča
 * @version 2009-02-25
 */
interface Modules {
    /**
     * Loads if neccessary module and creates instance and returns the instance
     * of module. Modules are loaded only once.
     *
     * @param String $module Name of the module to load.
     * @return Module Instance of loaded module. If module is not available,
     *         the method returns false.
     */
    public static function getModule($module);

    /**
     * Returns array of system names of all available modules.
     *
     * @return Array Names of all available modules.
     */
    public static function getModuleList();

    /**
     * Returns array containing details about desired module. Except for
     * details that may be obtained from module using getDetails method the
     * array contains three extra keys: installed - set to true if the module
     * is installed; system - set to true if the module is a system module;
     * administrable - set to true if the module has an administration
     * interface.
     *
     * @param String $module name of desired module.
     * @return Array Details of module. Returns false if the module is not
     *         available.
     */
    public static function getModuleDetails($module);

    /**
     * Resolves localized URL of module and returns system name of the Module.
     *
     * @param String $url localized module URL
     * @return String System name of module
     */
    public static function resolveModuleUrl($url);

    /**
     * Fires an event and delivers it to the modules.
     *
     * @param String $name Name of the event.
     * @param mixed $details Event data that will be delivered to the event
     *        handler.
     * @param String $source Name of module which fired the event.
     * @param String $target Name of module for which is the event assigned. If
     *        ommited, the event is delivered to all modules, that listen to
     *        events from source module. If event source is not specified, the
     *        event is delivered to all modules with appropriate event handler.
     * @param boolean $return Whether the caller is interested in return value.
     *        When false, the return value will not be retrieved and the method
     *        will not be executed using the pass-by-reference operator. False
     *        by default.
     * @return Array When firing a warning event, method returns array indexed
     *         by names of modules that has recieved warning with values that
     *         has returned their event handlers.
     */
    public static function &fireEvent($name, &$details, $source = '',
            $target = '', $return = false);
}
?>
